Skip to main content

Creating a Tracker

To create a tracker, you'll use the SDK's tracker creation function. Here's an example of creating the various tracker kinds:

from chariot import tracker as tracking_service

project_id = "<Project to create tracker(s) in>"

# Define a unitless point tracker
unitless_point_tracker = tracking_service.create_tracker(tracking_service.NewCreateTrackerRequest(
  project_id=project_id,
  kind=tracking_service.TrackerKind.POINT_UNITLESS,
  max_missing_updates=1,
  min_lifetime_before_active=1,
  assignment_function=tracking_service.TrackerAssignmentFunction.EUCLIDEAN,
  assignment_threshold=2.0,
))
print(f"Created Unitless Point Tracker with ID: {unitless_point_tracker.tracker_id}")

# Define a latitude/longitude point tracker
latitude_longitude_point_tracker = tracking_service.create_tracker(tracking_service.NewCreateTrackerRequest(
  project_id=project_id,
  kind=tracking_service.TrackerKind.POINT_LAT_LONG,
  max_missing_updates=2,
  min_lifetime_before_active=2,
  assignment_function=tracking_service.TrackerAssignmentFunction.HAVERSINE,
  assignment_threshold=10.0,
))
print(f"Created Latitude/Longitude Point Tracker with ID: {latitude_longitude_point_tracker.tracker_id}")

# Define a utm point tracker
utm_point_tracker = tracking_service.create_tracker(tracking_service.NewCreateTrackerRequest(
  project_id=project_id,
  kind=tracking_service.TrackerKind.POINT_UTM,
  max_missing_updates=3,
  min_lifetime_before_active=1,
  assignment_function=tracking_service.TrackerAssignmentFunction.EUCLIDEAN,
  assignment_threshold=100.0,
))
print(f"Created UTM Point Tracker with ID: {utm_point_tracker.tracker_id}")

# Define a unitless box tracker
unitless_box_tracker = tracking_service.create_tracker(tracking_service.NewCreateTrackerRequest(
  project_id=project_id,
  kind=tracking_service.TrackerKind.BOX_UNITLESS,
  max_missing_updates=1,
  min_lifetime_before_active=1,
  assignment_function=tracking_service.TrackerAssignmentFunction.INTERSECTION_OVER_UNION,
  assignment_threshold=0.5,
))
print(f"Created Unitless Box Tracker with ID: {unitless_box_tracker.tracker_id}")

# Define a latitude/longitude box tracker
latitude_longitude_box_tracker = tracking_service.create_tracker(tracking_service.NewCreateTrackerRequest(
  project_id=project_id,
  kind=tracking_service.TrackerKind.BOX_LAT_LONG,
  max_missing_updates=1,
  min_lifetime_before_active=1,
  assignment_function=tracking_service.TrackerAssignmentFunction.HAVERSINE,
  assignment_threshold=0.5,
))
print(f"Created Latitude/Longitude Box Tracker with ID: {latitude_longitude_box_tracker.tracker_id}")

When you run this, the object tracking service will create a new tracker instance on the platform with the given settings. The returned new_tracker object includes its tracker_id (a unique identifier). You should save this ID as you'll need it to reference the tracker in update and query calls.

note

You can create multiple trackers if needed (for example, one per video stream or one per object class). Just keep track of their IDs separately.

State Transition Modification​

The state transition matrix defines how the internal state of a tracker evolves from one time step to the next. Modifying this matrix allows you to customize how your motion model predicts the next state based on the current one.

Reasons to modify the state transition matrix:

  • Tune influence of state terms: Adjust weights between components (e.g., position vs. velocity) to control how dominant previous values are in the prediction.

  • Simulate specific physical constraints: You may encode decay, feedback, or even external forces by embedding them in the transition dynamics.

The following tracker kinds expect a state transition matrix of size 4x4: point_unitless, point_latitude_longitude, point_utm, and box_latitude_longitude. The box_unitless tracker kind expects a state transition matrix size of 7x7.

On creation a tracker's state transition matrix can be modified.

tracker_with_modified_state_transition = tracking_service.create_tracker(tracking_service.NewCreateTrackerRequest(
  project_id=project_id,
  kind=tracking_service.TrackerKind.POINT_UNITLESS,
  max_missing_updates=1,
  min_lifetime_before_active=1,
  assignment_function=tracking_service.TrackerAssignmentFunction.EUCLIDEAN,
  assignment_threshold=2.0,
  state_transition=[
    [50.0, 0.0, 1.0, 0.0],
    [0.0, 50.0, 0.0, 1.0],
    [0.0, 0.0, 10.0, 0.0],
    [0.0, 0.0, 0.0, 10.0],
  ]
))

Process Noise Covariance Modification​

The process noise covariance matrix models the uncertainty in how the state evolves. That is, it captures how much you "trust" your state transition model.

Reasons to modify the process noise covariance include:

  • Reflect system uncertainty: Increase variance to account for unpredictable or rapidly changing dynamics (e.g., erratic object motion).

  • Control filter responsiveness: A larger process noise covariance makes the filter more adaptive to measurements (less confident in prediction) while a smaller process noise covariance makes it more reliant on the internal model (more confident in prediction).
    A larger process noise covariance makes the filter more adaptive to measurements (less confident in prediction) while a smaller process noise covariance makes it more reliant on the internal model (more confident in prediction).

  • Match sensor characteristics: If you're fusing multiple sensor modalities, you might increase Q to let the filter lean more heavily on high-accuracy measurements.

  • Support multi-modal motion: If an object can abruptly switch behaviors (e.g., stop/start, zigzag), higher noise helps the filter respond to changes faster.

note

Tuning Q is often more impactful than tweaking the state transition matrix when trying to stabilize or improve tracker performance.

The following tracker kinds expect a process noise covariance matrix of size 4x4: point_unitless, point_latitude_longitude, point_utm, and box_latitude_longitude. The box_unitless tracker kind expects a process noise covariance matrix size of 7x7.

tracker_with_modified_process_noise_covariance = tracking_service.create_tracker(tracking_service.NewCreateTrackerRequest(
  project_id=project_id,
  kind=tracking_service.TrackerKind.POINT_UNITLESS,
  max_missing_updates=1,
  min_lifetime_before_active=1,
  assignment_function=tracking_service.TrackerAssignmentFunction.EUCLIDEAN,
  assignment_threshold=2.0,
  process_noise_covariance=[
    [10.0, 0.0, 1.5, 0.0],
    [0.0, 10.0, 0.0, 1.5],
    [0.0, 0.0, 1.0, 0.0],
    [0.0, 0.0, 0.0, 1.0],
  ]
))